The central core of Mildred is that it works solely with chunky-format graphics. This means that you have to somehow get the images into a format that can be displayed on your native AGA hardware. Such a conversion is known as `Chunky-to-Planar', also known as `c2p'.

The c2p system in Mildred can be a little complicated at times. First and foremost you have to reserve some memory for some c2pWindow structures. A c2pWindow is a definition of what size operation will be performed, the size of the source chunky buffer and importantly the size of the destination planar buffer.

It is important to note that any c2pWindows that you create are only valid if they share the same planar size. In most applications you would have one planar bitmap (with contigous bitplane memory, non-interleaved!) that is used for output throughout the program. You can specify new c2pWindows so that a different sized operation is performed, and you can even have a window that is smaller than the destination bitmap. But you cannot mix different sized planar bitmaps in the same program without having to recreate any c2pWindows you might want to use. This is due to the system having to self-modify some constant values within the c2p routine. It would be unwise and not very efficient to constantly remodify those values inside your game loop because it requires a cache-flush, although doing so is entirely possible if you so wish.

So, first of all you should reserve some memory for the c2pWindow structures using MReservec2pWindows, passing to it the total number of windows that you require. Note that objects are numbered from 0 upwards.

The c2p system of Mildred has interlacing facilities if you should need to use them, that allow a refresh to be split over more than one frame. It is possible to do row interlacing and also column interlacing, in which a column is 32 pixels wide. Also note that all width-related parameters in the c2p routines must be multiples of 32 pixels due to the c2p working in longwords. If you wish to use an interlaced c2p routine, you should make interlacing active BEFORE you create a c2pWindow, otherwise the window will not contain the correct information. For this purpose you can use either Mc2pRowLacing On/Off, or Mc2pColumnLacing On/Off.

You can get mildred to automatically `use' a c2pWindow object by calling MAutoUsec2pWindows On/Off, so that when you create a new c2pWindow object it will be used as the `current' c2pWindow, and can later be assumed by other routines to save you having to define which c2pWindow to use every time.

By this stage you are just about ready to create a c2pWindow, by using the Mc2pWindow statement. There is a short version which only requires the operation width and height to be passed, in which case it will assume that the source chunky buffer and the destination planar buffer are both precicely the same size. Further, you can pass blitz's `Processor' instruction which will tell the routine to globally set which version of the c2p to use. There is a special version for the 68030 cpu and also a version which works better for 68040 or higher. To make the c2pWindow definition more flexible you can also pass an alternative width for the source chunky buffer, the width of the planar destination buffer, and the height of the planar destination buffer. This allows you to create a c2pWindow that is smaller than the destination planar buffer, and also which may be smaller than the source buffer thus allowing you to directly display data from a chunky superbitmap, for example.

There is a kind of manual-override of the c2p's cpu mode which you can set with M040c2pUsage On/Off, which can enable or disable the 040+ c2p routine regardless of what/how else you tell it. If the 040 routine is disabled it will not be used under any circumstances. However, you don't need to worry about safety because the 040 c2p works on all 680X0 cpu's.

Once a c2pWindow has been created you can select to `use' it as the current c2pWindow object by using MUsec2pWindow or you can additionally set three current c2pWindows to use with MUsec2pWindows, to which you can pass one, two or three c2pWindows to use as current. Presently the system only has use for the first c2pWindow.

To optimally convert the chunky data depending on what CPU the user has available, you can tell the c2p system which routine to use with the statement Mc2pCPUmode, to which you should pass the blitz `Processor' instruction, in which 0 to 3 represents the 68030 routine, and 4 represents the 68040+ routine.

When it comes to telling the c2p system the address of your chunky buffer, in the Mc2p instruction, you can simplify matters somewhat by calculating an address based on an existing bitmap or shape object (see the relevant sections of this manual). Using the function MBitmapPtr you can easily provide an address based on the chunky Bitmap's base address, origin, clip window corner, and coordinate offset that you pass. There are also instructions for calculating an address based on a shape, a cookie, and a Bitmap's Stencil with MShapePtr, MStencilPtr and MCookiePtr.

By about this stage you should be ready to perform the actual chunky to planar data conversion which is done with a call to Mc2p. At its simplest you can just specify a Planar memory address, in which case the current c2pWindow is used and the current chunky Bitmap is used to calculate an address. In extension, you can supply a chunky memory address, which can be provided with a call to MBitmapPtr for example. You can also specify a particular c2pWindow to use if you wish. Using all of the information that has been provided to the system up to this point, the c2p routine can be performed and the defined window will be converted from chunky data to planar data so that you can see it on your AGA display. Mildred currently only works with 8-bit 256-colour chunky data, so you will need an AGA or graphics-card system for display purposes.

You can return the width of a previously created c2pWindow by calling Mc2pWindowWidth, or its height by calling Mc2pWindowHeight. Also, it is perfectly feasible to adjust the Height of a c2pWindow object once it has been created, by using Mc2pWindowNewHeight. This has been provided to allow you to adjust the height of the c2p operation in realtime. If you are using row-interlacing in the c2p system then note that the height will be rounded to a multiple of 2.

With c2p interlacing active, be it row lacing and/or column lacing, there are a variety of routines to handle the toggling of the long/short frames needed to alternate between odd/even rows/columns so that the screen is fully updated in the correct order. You can purposefully toggle the frame by using Mc2pRowToggle or Mc2pColumnToggle. You can also handle the interlacing amongst single, double and triple-buffered displays by using Mc2pToggleSingle, Mc2pToggleDouble and Mc2pToggleTriple. Note that double and triple-buffered displays will have an effect on lengthening the number of frames required to produce a full update of the display when c2p interlacing is operating.

To return the address of a c2pWindow structure, you can use MAddrc2pWindow, although if you modify any values in this way be careful that you know what you are doing. c2pWindow objects can be `freed' by using MFreec2pWindow, and all or a range of c2pWindows can be freed using MFreec2pWindows. The currently used main c2pWindow can be returned using the function MUsedc2pWindow. You can also duplicate a previously created c2pWindow object into a new c2pWindow object by using MCopyc2pWindowStruct, in which the window definition will be copied to a new c2pWindow object's definition.

One thing you should particularly note is that your planar output memory should be contiguous non-interleaved bitplanes. The c2p conversion will produce a scrambled output if you try to direct it at an interleaved bitmap's memory. I suggest reserving some memory large enough to hold your planar bitmap data, and then use blitz's CludgeBitmap instruction to create your bitmap. In AGA you should also be sure to align the base address to an 8-byte memory boundary so that the 64-bit datafetch can be used. Lower datafetches will have an impact on c2p conversion speed.

I shouldn't need to point out that normally you would keep your chunky data in fastram and your planar data in chipram, and that you need to perform a call to Mc2p in order to `see' the updated contents of the chunky data buffer.